Documentation Version for Comments and Changes

You are invited to make any changes...add any comments.

Changes will `eventually` be merged into the offical documentation.

Leave any commnents here...

...

... back to index page OE documentation

---

---

At the top of your program, so you can start tracing from the beginning of execution. More commonly, you will want to trigger tracing when a certain routine is entered, or when some condition arises. e.g.

if x < 0 then 
    trace(1) 
end if 

You can turn off tracing by executing a trace(0) statement. You can also turn it off interactively by typing 'q' to quit tracing. Remember that with trace must appear outside of any routine, whereas trace can appear inside a routine or outside.

You might want to turn on tracing from within a type. Suppose you run your program and it fails, with the ex.err file showing that one of your variables has been set to a strange, although not illegal value, and you wonder how it could have happened. Simply create a type for that variable that executes trace(1) if the value being assigned to the variable is the strange one that you are interested in. e.g.

type positive_int(integer x) 
    if x = 99 then 
        trace(1) -- how can this be??? 
        return 1 -- keep going 
    else 
        return x > 0 
    end if 
end type 

When positive_int returns, you will see the exact statement that caused your variable to be set to the strange value, and you will be able to check the values of other variables. You will also be able to check the output screen to see what has happened up to this precise moment. If you define positive_int so it returns zero for the strange value (99) instead of one, you can force a diagnostic dump into ex.err.

Remember that the argument to trace does not need to be a constant. It only needs to be 0, 1, 2 or 3, but these values may be the result from any expression passed to trace. Other values will cause trace to fail.

Trace Screen

When a trace(1) or trace(2) statement is executed by the interpreter, your main output screen is saved and a trace screen appears. It shows a view of your program with the statement that will be executed next highlighted, and several statements before and after showing as well. You cannot scroll the window further up or down though. Several lines at the bottom of the screen are reserved for displaying variable names and values. The top line shows the commands that you can enter at this point:

Command	Action
F1	display main output screen take a look at your program's output so far
F2	redisplay trace screen. Press this key while viewing the main output screen to return to the trace display.
Enter	execute the currently-highlighted statement only
down-arrow	continue execution and break when any statement coming after this one in the source listing is about to be executed. This lets you skip over subroutine calls. It also lets you stop on the first statement following the end of a loop without having to witness all iterations of the loop.
?	display the value of a variable. After hitting ? you will be prompted for the name of the variable. Many variables are displayed for you automatically as they are assigned a value. If a variable is not currently being displayed, or is only partially displayed, you can ask for it. Large sequences are limited to one line on the trace screen, but when you ask for the value of a variable that contains a large sequence, the screen will clear, and you can scroll through a pretty-printed display of the sequence. You will then be returned to the trace screen, where only one line of the variable is displayed. Variables that are not defined at this point in the program cannot be shown. Variables that have not yet been initialized will have "< NO VALUE >" beside their name. Only variables, not general expressions, can be displayed. As you step through execution of the program, the system will update any values showing on the screen. Occasionally it will remove variables that are no longer in scope, or that haven't been updated in a long time compared with newer, recently-updated variables.
q	quit tracing and resume normal execution. Tracing will start again when the next trace(1) is executed.
Q	quit tracing and let the program run freely to its normal completion. trace statements will be ignored.
!	this will abort execution of your program. A traceback and dump of variable values will go to ex.err.

As you trace your program, variable names and values appear automatically in the bottom portion of the screen. Whenever a variable is assigned to, you will see its name and new value appear at the bottom. This value is always kept